3D Star Map v1.21
Written by David McMurray 2000

Release information

Version 1.00	02-05-2000	Initial release of 3D Star Map freeware.
Version 1.10	29-05-2000 	System search, nearest system and nearest owned system
				Features added, including race names.
Version 1.20	30-09-2000	Nearest not owned feature added, an extra 6 race
				colours added allowing up to 14 races. Configurable time and
				distance units, and the option to include resource production per
				time unit, and current stockpiled resources.
Version 1.21	03-10-2000	Time unit resets to Year regardless of what the user defined in
				the map file, when the system updates the display, bug fixed.
Version 1.30	17-08-2001	The ownership of a system and the symbol which represents it can
				now be changed within the program, rather than editing the map
				file directly.


Updates

You can now receive news of any new updates or applications by sending an e-mail to me at 
sauron@innotts.co.uk with subscribe # to saurons development news in the subject line (excluding 
the quotes, and replacing the # with your e-mail address). You will receive a confirmation e-mail when 
I have added you to the list. If you do not receive a confirmation e-mail within 7 days, then please re-
submit your request.

To be removed from the list simply send a message to the e-mail address above with unsubscribe # 
from saurons development news in the subject line (excluding the quotes, and replacing the # with 
your e-mail address). Again you will receive a confirmation e-mail when I have processed your 
request. If you do not receive a confirmation e-mail within 7 days, then please re-submit your request.


Introduction

What is 3D Star Map? Well, it is actually the beginning of a campaign client program, which I am 
currently developing. Primarily this project is for use with Full Thrust, a tabletop miniatures game of 
space combat by Jon Tuffley and Ground Zero Games, but the program could easily be used for other 
games of this genre. Once the campaign programs have been completed you will be able to obtain them 
from http://www.innotts.co.uk/~sauron. 

For now the client is available as this 3D star map viewer, enabling you to run campaigns using a 3D 
map for that extra realism. This document aims to explain how to use the software, and its simple 
interface.

If you encounter problems using this program, or have any ideas on how to improve it, Id be glad to 
hear from you. Please e-mail me at sauron@innotts.co.uk. 

This program has been tested on a windows 32-bit platform only, although there shouldnt be any 
reason why it wont work on a 16-bit windows environment, therefore it should work on Windows 
95/98/NT/2000. Nevertheless, I cannot be held responsible for any problems that may arise due to the 
installation and/or running of this software. If you choose to install and run this software then the 
responsibility lies with you, the user, should it have any detrimental effects on your system.


Installation & Set-up

Installing and setting up this software is very easy, simply extract the self-extracting (I know, I know, it 
sounds weird) executable called Setupex.exe from the programs zip file, into a temporary directory. 
Then double click on the aforementioned file and follow the installation instructions provided by the 
set-up program, couldnt be easier (he says).

Once the installation is complete, you can start the program in several ways, e.g. by double-clicking on 
the executable file in windows explorer, or clicking on the icon in the windows Start menu (If you 
specified having the icon added to the start menu during installation) for example.


Using the software

When running the program for the first time, without any alteration to the 3dstarmap.ini file, you 
should see the test map in 3D. You can rotate the map up/down and left/right by holding down the right 
mouse button whilst the mouse cursor is on the map, and then moving the mouse forward/backward 
and left/right.

To view other map files simply change the filename in 3dstarmap.ini to the name of your map file and 
restart the program.

You can zoom in/out of the map simply by holding down both left and right mouse buttons whilst the 
mouse cursor is on the map, ad moving the mouse forwards to zoom in, and backwards to zoom out.

Please note: The brighter half of the inner circle represents the side closest to you, and the dimmer side 
is further away. This is to help you determine whether you are viewing the map from below or from 
above, without this it is easy to get confused.

You may notice that the star systems displayed are in several different colours, these colours represent 
their alliance with a particular race. Therefore you can easily see which systems belong to which 
player.

To exit the program at any time press the Esc key, which should display a menu. From here you can 
click on Resume to continue using the map, or Exit to close the program.

Now, the real use for the program lies in being able to find distances between star systems, enabling 
you to determine how long it will take your ships to travel from one star system to another. The 
distances are given in light years, but of course you can interpret the values as any unit of distance you 
like. These values are taken from the systems co-ordinates specified in the map file which use the same 
unit of distance as given in this program, creating your own map file data will be explained later.

You can select a system simply by clicking on it on the map; this will highlight it with a large circle, 
and a line extending vertically to the central horizontal plane. This is to help you see the systems 
position a little more clearly. Once you select a system it will also display its name in the top left corner 
of the screen, in its races designated colour, and below that you will see the name of the 
race/nationality which owns that system. If you now click on another system the previous system is 
now unselected and the new system is highlighted. Clicking on the map but not on or near a system 
will deselect any currently selected system(s).

To display the distance between a star and other stars, select the first star then hold down the Shift 
key and select a destination star. You will notice how both stars are now selected and a line has 
appeared between them following the shortest distance. The names of both systems and the distance 
between them are now displayed in the top left corner of the map. You can change the destination 
system to another simply by holding down the Shift key again and clicking on another system, you do 
not need to specify the first system again.

At the top of the display you should find a menu bar, with the buttons Search Systems, Nearest 
System, Nearest Owned and Nearest Not Owned.

If you click on the  Search Systems button, a list of all the systems on the map will be displayed in 
alphabetical order by system name. When you have found the system you are searching for, simply 
select its name in the list and then click on the OK button. If no systems were selected when choosing 
Search Systems then your chosen system will now be highlighted on the map, and its details 
displayed under the menu bar. If a system was already selected before the search, then the original 
system and the newly searched system will both be selected, and the distance between them displayed 
under the menu bar, further searches will simply change the destination system.

Clicking on Nearest System, Nearest Owned and Nearest Not Owned without having a star 
selected will not do anything, you must first select a star. Clicking on Nearest System will then 
highlight and display the distance to the nearest system to your first selected star, regardless of who 
owns either system.

Clicking on Nearest Owned with a star already selected will highlight and display the distance to the 
nearest system owned by the same race/nationality as the first star selected, if there are no other owned 
systems you should hear a warning beep and no other systems will be selected.

Clicking on Nearest Not Owned with a star already selected will highlight and display the distance to 
the nearest system owned by another race/nationality, or not owned at all. If there are no other non-
owned systems (i.e. this race/nationality owns all the systems on the map) then you should hear a 
warning beep and no other systems will be selected.
Well, thats about it for the interface, its not a great deal but it can have its uses in a campaign 
capacity, so its up to you how you use it.

The ownership of a system, i.e. the race name associated with it, and the symbol used to represent it on
the map can be changed. Simply select the system you wish to change, only one system should be selected
for this, and then press the 'P' key on your keyboard. A 'System Properties' box will appear showing a
list of all the race names with the current race for that system highlighted, and 3 buttons representing
the 3 symbols available for a system to be displayed as on the map, i.e. circle, square and diamond. One
of these will be a filled shape indicating that this is the current symbol being used for the selected
system.

You can select an alternative race from the list, and an alternative symbol by clicking on them with the
mouse pointer. Once you are satisfied with the changes click on the 'OK' button, or if you change your
mind and wish to leave the properties unchanged click on 'Cancel'.

If you selected a different race and/or different symbol and then clicked on the 'OK' button, you will now
see that the new properties of the selected system are now displayed on the map. Also your map file has
been updated with the new information. It is therefore advisable to create a backup of your map file
before starting to make changes, just in case you make some mistakes and then find that you can't remember
what the values were originally. If you make a backup of your map file you can always revert back to that
if you make a mistake altering the properties of systems.


Map files

There should be a test map file included with this distribution named test.map, but of course you can 
create your own. To do this all you need is a text editor, Notepad is fine for this.

Map files created for version 1.00 and 1.10 will not work directly with version 1.20. Since version 1.00 
and 1.10 map files contained only a subset of that required by the latest version, version 1.20 requires 
some extra information adding to the map file.

The first line has been reserved for activating/deactivating options available in the program, currently 
there is only one option, namely Resource Monitoring. To turn resource monitoring on, enabling the 
program to display system resource stats, place a 1 at the beginning of the first line. To deactivate 
resource monitoring place a 0 at the start of the first line instead.

The second line should contain the unit of distance measurement to be used, i.e. Light Years, or Parsecs 
etc.

The third line should contain the unit of time measurement to be used, i.e. if your game turns are a year 
long you would enter Year on this line, etc.

The next 14 lines of the map file should contain the names of the different races/nationalities, it is 
advised that the first of these is None to show systems not owned by anyone in white, the other 13 
lines can be whatever you like. If you do not wish to use all 14 slots any unused ones should be set to 
None, but you must always use the these 14 lines for these names. For an example of how the file is 
laid out simply load the test.map file into a text editor like notepad.

Each line of the file after the race/nationalities is a separate star system and contains stats separated by 
commas. The first three values represent the x, y and z co-ordinate position of the system respectively, 
these values are floating point types and can be negative, for example 12.04,-6,-11.982. The maximum 
and minimum allowed values are pretty extreme so there should be no worry of going out of range, but 
if you use light years as the measuring units you shouldnt need to use very large or very small 
numbers anyway, the example map should give you some idea. Also you do not need to have 0,0,0 as 
the centre of the map, the program will automatically calculate the centre from its boundaries and 
normalise the map itself.

The next value is a number between 0 and 13, and depicts the race that currently owns that system; this 
is directly related to the different colours available on the map. If you cant wait for the full campaign 
client, and you have some programming ability, you could write a program that allows you to read the 
map file, edit the race number and save it again. Thus allowing you to change ownership of the systems 
as your players battle it out, stealing systems from each other.

After that is the system name, which for obvious reasons cannot contain a comma, but other than that is 
fairly flexible, except to say that it is limited to 256 characters ;).

The next value can be one of three numbers, namely 0, 1 or 2. These select a different symbol to 
represent the system on the map. A value of 0 will display the system as a circle, a value of 1 will 
display the system as a square, and a value of 2 displays the system as a diamond. This feature has been 
implemented with the Client program in mind, and the three symbols are for representing a status for 
that system. But you can use it to represent whatever you want, such as to show which systems have a 
shipyard, or to show that a new ship has been built this turn, etc. its really up to you at this point.

The next value is really for use in the campaign client program, and actually represents the number of 
resource points produced each game turn. This is to be directly related to the NPV values used in the 
Full Thrust game by Jon Tuffley and Ground Zero Games, of course you can use it for whatever 
purpose you like for the time being. The map program doesnt actually use this value yet anyway 
except that it is displayed when resource monitoring is enabled and a single system is selected.

The final value is again implemented for the campaign client, but may be useful as it is for campaign 
games. This value represents how many resource points are currently stockpiled at this system, and is 
displayed when a single system is selected and resource monitoring has been enabled. As a final note, a 
comma is not required at the end of each line.

Note: Remember to change the filename in 3dstarmap.ini to the filename of your map.


Well thats it for the instructions, I hope theyre not too confusing or riddled with errors, if you do 
experience any problems then please drop me an e-mail to sauron@innotts.co.uk, and I will endeavour 
to fix any bugs ASAP, or reply with any help I can.


Legal stuff

This software is the sole copyright of David McMurray 2000, and is distributed as freeware provided 
credit remains with David McMurray, and all parts of the software remain in the distribution, and 
this file remains unaltered. You may add extra information to this file, documenting any changes you 
may have made, but I request that any information currently held within remain unchanged.


Contact

David McMurray
E-mail : sauron@innotts.co.uk
Webpage : http://www.innotts.co.uk/~sauron


